-
Notifications
You must be signed in to change notification settings - Fork 58
PORT-14552 - Docs for Github ocean integration #2494
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
This pull request is automatically being deployed by Amplify Hosting (learn more). |
…bs/port-docs into PORT-14552-document-github-ocean
…-document-github-ocean
…-document-github-ocean
…-document-github-ocean
…-document-github-ocean
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Outdated
Show resolved
Hide resolved
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Outdated
Show resolved
Hide resolved
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md
Outdated
Show resolved
Hide resolved
:::info repository type | ||
|
||
The `repositoryType` parameter filters which repositories are ingested. It corresponds to the `type` parameter in GitHub's [List organization repositories](https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28#list-organization-repositories) API. | ||
|
||
<details> | ||
<summary>Possible values:</summary> | ||
|
||
* `all` (default): All repositories accessible to the provided token. | ||
* `public`: Public repositories. | ||
* `private`: Private repositories. | ||
* `forks`: Only forked repositories. | ||
* `sources`: Only non-forked repositories. | ||
</details> | ||
|
||
::: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
please move this to be inside the appConfig collapsible, currently it is not very clear what it refers to.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @hadar-co where do I find more information about this appConfig? My searches don't seem to turn up any useful information.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i meant the snippet that follows right after the callout. I remember that it had this repositoryType param, but now i see that it doesnt. Did you remove it intentionally?
In my comment I meant that it makes sense to explain what repositoryType is in the same place where it appears, so there's context.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, I get you now. I moved it to the integration home page as part of the configuration documentation can you check it out? I initially had it in the examples app config, it did not look very nice.
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Outdated
Show resolved
Hide resolved
import PortApiRegionTip from "/docs/generalTemplates/\_port_region_parameter_explanation_template.md" | ||
import InstallMethods from "./\_install_methods.mdx" | ||
|
||
# Github App |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we need another page for installing the github app? why not use the existing docs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a custom app installation
The user creates a custom app with permissions which is later re-configured by the integration itself.
The existing github app installation is just setting up the monorepo's installation
@melodyogonna @emekanwaoma correct me if im wrong
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hadar-co it has steps (and images) on how to create the app rather than just how to install it. I felt it warranted another page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@matan84 @melodyogonna
I see, so the installation/configuration is different from the regular app? If so, let's clarify that this is a custom app with some manual configuration
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is similar to the Github app setup documented here for the existing Github Cloud App: https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation
Except a few steps in the setup are removed, and the deployment is expanded.
...our-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx
Outdated
Show resolved
Hide resolved
...our-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Left a few recommendations
...ld-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx
Show resolved
Hide resolved
.../sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx
Outdated
Show resolved
Hide resolved
...g/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_file_repo_app_config.mdx
Outdated
Show resolved
Hide resolved
...our-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx
Outdated
Show resolved
Hide resolved
...our-software-catalog/sync-data-to-catalog/git/github-ocean/installation/_install_methods.mdx
Outdated
Show resolved
Hide resolved
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Outdated
Show resolved
Hide resolved
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Outdated
Show resolved
Hide resolved
docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md
Show resolved
Hide resolved
- Only JSON and YAML formats are automatically parsed. | ||
Other file formats can be ingested as raw files, however, some special characters in the file (such as `\n`) may be processed and not preserved. | ||
|
||
## Permissions |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's put it as one of the first if not the first paragraph of the integration page
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hadar-co Also would love your opinion here
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@matan84 I'm not sure I understand, should I move the capabilities example further up the page? This is part of a larger content.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@matan84 you're talking about the permissions header, right? If so, perhaps we can call it "Prerequisites" instead and move it to be before "Setup". WDYT?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like calling it prerequisites
and putting it above Setup
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@hadar-co I'm wondering if this isn't redundant information, there is a required permissions
in the installation page as well, I think that is a much better place to have it. My instinct is to remove this entirely.
…-document-github-ocean
…bs/port-docs into PORT-14552-document-github-ocean
0eee868
to
59ccbd2
Compare
…-document-github-ocean
Co-authored-by: hadar-co <[email protected]>
Co-authored-by: hadar-co <[email protected]>
…-document-github-ocean
…bs/port-docs into PORT-14552-document-github-ocean
Description
This is the initial docs for the new Github integration powered by Ocean framework.
Added docs pages
/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/
)/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation
)/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/self-hosted-installation
)/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/resource-mapping-examples
)